{
    title:  "MakeMe DOM",
    crumbs: [
        { 'Reference Guide': 'index.html' },
    ],
}

        <h1>MakeMe DOM</h1>
        <p>The MakeMe DOM allows you to access and manipulate the entire MakeMe model for how to build a project. Every 
        target, rule and dependency are all stored and exposed via the MakeMe DOM.</p>
       
        <p>The DOM is created by loading one or more MakeMe files that provide portions of the DOM. Some of these MakeMe
        files are provided internally by MakeMe to define operating system specific semantics and one or more are provided
        by the user. All are blended into a single DOM object.</p>
        <h2>DOM Root</h2>
        <p>The root of the MakeMe DOM is a singleton global object called <em>me</em>. From it, all properties of the DOM
        are accessible.  To see the entire DOM for your project, run: </p>
<pre class="ui code segment">$ <b>me --dump</b>
[Dump] Save MakeMe DOM to: macosx-x64-debug.dmp
</pre>
        
        <a name="top"></a>
        <h2>Top Level &mdash; me.*</h2>
        <p>Here is a non-exhaustive description of the important top-level MakeMe property collections. 
        <table title="top-level collections" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>blend</td><td>MakeMe files to blend. 
                    This is an array of files to load. These paths may include the wild-card "*" character to 
                    match a filename portion and "**" to match any file or directory at any depth in the directory 
                    tree. If the filename is not found, "~/.paks" is searched for a matching Pak.</td></tr>
                <tr><td>customize</td><td>Optional MakeMe files to load after fully loading all blended MakeMe files</td></tr>
                <tr><td>defaults</td><td>Default properties to be inherited by all targets</td></tr>
                <tr><td>dir</td><td>Directories used by MakeMe. These must be absolute paths so that they can be used
                    when the current directory is changed while processing.
                    <ul>
                        <li>work &mdash; Path to the current directory from where MakeMe is being initiated</li>
                        <li>top &mdash; Path to the top of the source to build</li>
                        <li>src &mdash; Path to a "src" directory under top where the pure source code lives</li>
                        <li>home &mdash; User's home directory</li>
                        <li>bld &mdash; Build output directory under "work"</li>
                        <li>out &mdash; Platform output directory under the "bld" directory</li>
                        <li>bin &mdash; Platform output executables and libraries directory under the "out" directory</li>
                        <li>inc &mdash; Platform includes "inc" directory under the "out" directory</li>
                        <li>obj &mdash; Platform objects directory under the "out" directory</li>
                        <li>me &mdash; Path to the MakeMe product scripts directory</li>
                    </ul>
                </td></tr>
                <tr><td>env</td><td>Environment variables to set when compiling and linking</td></tr>
                <tr><td>ext</td><td>File extensions indexed by file type</td></tr>
                <tr><td>globals</td><td>Global values to use in property token expansion</td></tr>
                <tr><td>internal</td><td>Default properties to be inherited by only the targets in the same MakeMe file</td></tr>
                <tr><td>main</td><td>Path to the <em>main.me</em> file. Used in platform MakeMe files.</td></tr>
                <tr><td>mixin</td><td>Literal script code to mixin.</td></tr>
                <tr><td>modules</td><td>List of scripts or compiled scripts to pre-load</td></tr>
                <tr><td>options</td><td>Supplied command line options</td></tr>
                <tr><td>platform</td><td>Description of the current platform. Has properties for operating system
                        and CPU architecture.</td></tr>
                <tr><td>plugins</td><td>List of required plugins. These are listed without '.me' extensions.</td></tr>
                <tr><td>prefixes</td><td>Installation directory prefixes and default values on Unix/Linux systems:
                    <ul>
                        <li>root &mdash; Root directory prefix: /</li>
                        <li>base &mdash; Base installation prefix: /usr/local</li>
                        <li>data &mdash; Installation prefix for modifiable data: /</li>
                        <li>state &mdash; Base installation prefix: /var</li>
                        <li>app &mdash; Base application directory: /usr/local/lib/${settings.product}</li>
                        <li>vapp &mdash; Versioned application directory: ${prefixes.product}/${settings.version}</li>
                        <li>etc &mdash; Configuration prefix: ${prefixes.data}/etc/${settings.product}</li>
                        <li>bin &mdash; Binary directory: ${prefixes.base}/bin</li>
                        <li>inc &mdash; Include directory: ${prefixes.base}/include</li>
                        <li>lib &mdash; Product libraries: ${prefixes.base}/lib</li>
                        <li>man &mdash; Product log files: ${prefixes.base/share/man</li>
                        <li>sbin &mdash; System binaries: ${prefixes.base}/sbin</li>
                        <li>log &mdash; Product log files ${prefixes.state}/log/${settings.product}</li>
                        <li>spool &mdash; Product spool files ${prefixes.state}/spool/${settings.product}</li>
                        <li>cache &mdash; Product spool files ${prefixes.state}/cache/${settings.product}</li>
                        <li>web &mdash; Product log files ${prefixes.state}/www/${settings.product}-default</li>
                        <li>src &mdash; Product source /usr/src/${settings.product}-${settings.version}</li>
                    </ul>
            
            </td></tr>
                <tr><td>profiles</td><td>Build profiles. Standard profiles are: debug and release</td></tr>
                <tr><td>rules</td><td>Command rules for compiling, building libraries and executables</td></tr>
                <tr><td>scripts</td><td>Project top-level scripts.</td></tr>
                <tr><td>settings</td><td>Project top-level settings. This includes name, version, description. 
                        See <a href="#settings">settings</a> collection below for full details.</td></tr>
                <tr><td>target</td><td>Reference to the currently building target.</td></tr>
                <tr><td>targets</td><td>Targets to build. Each target is its own collection of properties</td></tr>
                <tr><td>usage</td><td>Additional usage message to emit for MakeMe command line errors</td></tr>
            </tbody>
        </table>
        <a name="globals"></a>
        <h2>Globals &mdash; me.globals.*</h2>
        <p>The following me.globals.* are defined for use by tokens:</p>
        <table title="globals" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
            <tr><td>ARCH</td><td>CPU architecture: x86, x64, ppc, ...</td></tr>
            <tr><td>BIN</td><td>Binary outputs directory: OS-ARCH-PROFILE/bin</td></tr>
            <tr><td>BLD</td><td>Build output directory</td></tr>
            <tr><td>CONFIG</td><td>Platform configuration: OS-ARCH-PROFILE</td></tr>
            <tr><td>EXE</td><td>Executable extension: .exe</td></tr>
            <tr><td>GCC_ARCH</td><td>CPU architecture mapped to a GCC architecture: x86_64, i686, ...</td></tr>
            <tr><td>LIKE</td><td>Set to windows or posix if relevant</td></tr>
            <tr><td>INC</td><td>Standard include directory</td></tr>
            <tr><td>LBIN</td><td>Binary output directory for the local platform</td></tr>
            <tr><td>O</td><td>Compiled object file extension: .o, .obj</td></tr>
            <tr><td>OBJ</td><td>Directory holding compiled files: OS-ARCH-PROFILE/obj</td></tr>
            <tr><td>OS</td><td>Operating system: linux, windows, ...</td></tr>
            <tr><td>OUT</td><td>Per-platform output directory: build/OS-ARCH-PROFILE</td></tr>
            <tr><td>PAKS</td><td>Local Paks directory: src/paks</td></tr>
            <tr><td>PKG</td><td>Package directory: build/OS-ARCH-PROFILE/pkg</td></tr>
            <tr><td>PLATFORM</td><td>Platform string: OS-ARCH</td></tr>
            <tr><td>PROFILE</td><td>Selected build profile. Typically 'debug' or 'release'</td></tr>
            <tr><td>PROJ</td><td>Generated projects directory. Typically 'projects'</td></tr>
            <tr><td>REL</td><td>Release image directory: build/OS-ARCH-PROFILE/img</td></tr>
            <tr><td>SHLIB</td><td>Shared object library extension: .so, .lib</td></tr>
            <tr><td>SHOBJ</td><td>Shared object extension: .so, .dll</td></tr>
            <tr><td>SRC</td><td>Directory of the source tree to be built</td></tr>
            <tr><td>TOP</td><td>Top directory where the project is being built</td></tr>
            </tbody>
        </table>
        
        <a name="platform"></a>
        <h2>Platform Collection &mdash; me.platform.*</h2>
        <p>The platform collection defines properties for:
        <table title="platform collection" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>arch</td><td>CPU architecture: arm, ppc, x64, x86, ...</td></tr>
                <tr><td>like</td><td>Set to 'windows' or 'posix' or empty</td></tr>
                <tr><td>os</td><td>Operating system: linux, windows, vxworks, ...</td></tr>
                <tr><td>profile</td><td>Build profile selected: 'debug', 'release', ...</td></tr>
            </tbody>
        </table>
        <a name="configure"></a>

        <h2>Configure Collection &mdash; me.settings.*</h2>
        <p>The configure collection specifies the configurable targets used to extend the project.</p>
        <table title="settings" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>discovers</td><td>List of optional configurable components to discover when configuring </td></tr>
                <tr><td>requires</td><td>List of required components to discover when configuring </td></tr>
                <tr><td>extras</td><td>List of components that but can be included via an explicit
                    <em>configure --with NAME</em> command.</td></tr>
            </tbody>
        </table>
        <a name="settings"></a>
        <h2>Settings Collection &mdash; me.settings.*</h2>
        <p>The settings collection specifies the top level project/product names. It is required in the main.me file.</p>
        <table title="settings" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>company</td><td>Company name</td></tr>
                <tr><td>prefixes</td><td>Name of collection containing installation prefixes. 
                    Set to debian|embedthis|opt or to a user-provided collection. This causes the requested prefix collection
                    to be copied to the prefixes collection.</td></tr>
                <tr><td>product</td><td>Product or project name. Should be one word, lower case without spaces</td></tr>
                <tr><td>static</td><td>Build using static linking instead of building shared libraries</td></tr>
                <tr><td>title</td><td>Descriptive one sentence title for the product</td></tr>
                <tr><td>version</td><td>Product version string. Should be of the form: MAJOR.MINOR.PATCH </td></tr>
            </tbody>
        </table>
        <a name="targets"></a>
        <h2>Targets Properties &mdash; me.targets[].*</h2>
        <table title="targets" class="ui table segment">
            <thead>
                <tr><th>Name</th><th>Description</th>
            </thead>
            <tbody>
                <tr>
                    <td>compiler</td>
                    <td>Array of compiler options</td>
                </tr>
                <tr>
                    <td>configurable</td>
                    <td>Boolean set to true if the target is a configurable target used during the 
                    configure phase.</td>
                </tr>
                <tr>
                    <td>defines</td>
                    <td>Array of compiler pre-processor definitions</td>
                </tr>
                <tr>
                    <td>depends</td>
                    <td>Array of other targets that are used by this target. Dependencies are built first.
                    The defines, includes, libraries and other properties of the depended upon targets
                    are inherited by the target.</td>
                </tr>
                <tr>
                    <td>enable</td>
                    <td>Ejscript expression to evaluate to a boolean. Enable the target if true.
                        This must be a quoted string to delay execution. Otherwise it will be evaluated when the
                        MakeMe file is first loaded.</td>
                </tr>
                <tr>
                    <td>exclude</td>
                    <td>Regular expression of file patterns to exclude from the sources list
                    This is a filter that is applied to the sources list after expanding the sources wildcards</td>
                </tr>
                <tr>
                    <td>goals</td>
                    <td>Array of goal targets for which this target will be built. This will typically
                    include the name of the target itself. Other possible goals are: 'all' for default builds, 
                    'generate' for targets that should be included in project generation.</td>
                </tr>
                <tr>
                    <td>headers</td>
                    <td>Header files to export to the platform/inc directory.</td>
                </tr>
                <tr>
                    <td>home</td>
                    <td>Home directory to use when resolving paths for this target</td>
                </tr>
                <tr>
                    <td>ifdef</td>
                    <td>List of targets that are needed by this target.  The target will not be built
                    if any of the specified targets are missing or not enabled.</td>
                </tr>
                <tr>
                    <td>include</td>
                    <td>Regular expression of file patterns to include from the sources list. 
                    This is a filter that is applied to the sources list after expanding the sources wildcards</td>
                </tr>
                <tr>
                    <td>includes</td>
                    <td>Array of compiler include directories</td>
                </tr>
                <tr>
                    <td>libraries</td>
                    <td>Array of libraries to link</td>
                </tr>
                <tr>
                    <td>libpaths</td>
                    <td>Array of link library search paths</td>
                </tr>
                <tr>
                    <td>linker</td>
                    <td>Array of linker options</td>
                </tr>
                <tr>
                    <td>message</td>
                    <td>Message to display when building. Should be of the form: "Tag: Message".</td>
                </tr>
                <tr>
                    <td>name</td>
                    <td>Target name. This name is used rather than the collection name</td>
                </tr>
                <tr>
                    <td>path</td>
                    <td>Path to the result of building the target. If unset, MakeMe computes the output path
                        based on the target name and the target type. If the path is set, it overrides the default
                        and defines the output filename or directory for the target.</p>
                </tr>
                <tr>
                    <td>platforms</td>
                    <td>Platforms for which this target should be built. Set to OS-ARCH or <em>local</em>
                        for the local platform.</td>
                </tr>
                <tr>
                    <td>rule</td>
                    <td>Build command template to use when invoking compiler and linker. Typically not
                        explicitly set unless overriding for some reason. Set to: 'c-&gt;o', 'cpp-&gt;o', 'lib', 'exe', 'gui'. Rules are automatically selected for 'lib' and 'exe' targets. </td>
                    </tr>
                <tr>
                    <td>scripts</td>
                    <td>Scripts for the target. See <a href="#scripts">scripts</a> for details.</td>
                </tr>
                <tr>
                    <td>sources</td>
                    <td>Array of source file patterns to compile for the target. Use normal * as a
                        wild-card, ** as a wild-card that descends directories. Use the exclude property to exclude </td>
                </tr>
                <tr>
                    <td>type</td>
                    <td>Type of target: exe, lib, action, obj, header, build and custom values.
                    <ul>
                        <li>exe &mdash; Executable type</li>
                        <li>lib &mdash; Library type</li>
                        <li>obj &mdash; Object type from compiled source. These are dynamically created from 
                            the sources property.</li>
                        <li>header &mdash; Headers are dynamically discovered and created from source files.</li>
                        <li>action &mdash; Script type that is run when explicitly specified as a target on the 
                            MakeMe command line, or as a dependency for another target.</li>
                        <li>build &mdash; Script type that is run for default builds.</li>
                        <li>custom values &mdash; Targets may be set to any custom type. If MakeMe is invoked with a
                            type specified as a target, then all the targets of that type will be run.</li>
                    </ul>
                    </td>
                </tr>
                <tr>
                    <td>uses</td>
                    <td>Soft dependency. Array of other targets that may be used by this target. 
                    The specified targets are built first if enabled. This target will be built regardless of whether
                    the targets specified in "uses" are present or enabled or not.
                    The defines, includes, libraries and other properties of the depended upon targets
                    are inherited by the target.</td>
                </tr>
            </tbody>
        </table>

        <a name="files"></a>
        <h2>Additional Target Properties for File Targets &mdash; me.targets[].*</h2>
        <table title="targets" class="ui table segment">
            <thead>
                <tr><th>Name</th><th class="two wide">Type</th><th>Description</th>
            </thead>
            <tbody>
                <tr>
                    <td>active</td>
                    <td>Boolean</td>
                    <td>If a destination file is an active executable or library, rename the active file using 
                        a '.old' extension and retry.</td>
                </tr>
                <tr>
                    <td>append</td>
                    <td>Boolean</td>
                    <td>Set the operation to catenate input files into a single output file. Same as 
                        'operation: "append"'</td>
                </tr>
                <tr>
                    <td>compress</td>
                    <td>Boolean</td>
                    <td>Compress destination files using Zlib. Results in a '.gz' extension.</td>
                </tr>
                <tr>
                    <td>divider</td>
                    <td>String</td>
                    <td>Divider text to use between appended files.</td>
                </tr>               
                <tr>
                    <td>extension</td>
                    <td>String | Path</td>
                    <td>Extension to use for the destination filenames.</td>
                </tr>
                <tr>
                    <td>extensionDot</td>
                    <td>String</td>
                    <td>Specifies where the filename extension begins for filenames with multiple dots. 
                        Set to 'first' or 'last'.</td>
                </tr>
                <tr>
                    <td>filter</td>
                    <td>RegExp</td>
                    <td>Pattern of lines to filter out from appended files.</td>
                </tr>
                <tr>
                    <td>flatten</td>
                    <td>Boolean</td>
                    <td>Flatten the input source tree to a single level. Defaults to true.</td>
                </tr>
                <tr>
                    <td>footer</td>
                    <td>String</td>
                    <td>Footer to append when appending files.</td>
                </tr>
                <tr>
                    <td>group</td>
                    <td>String | Number</td>
                    <td>Group permission name or number to use for the destination files.</td>
                </tr>
                <tr>
                    <td>header</td>
                    <td>String</td>
                    <td>Header prepend when appending files.</td>
                </tr>
                <tr>
                    <td>isDir</td>
                    <td>Boolean</td>
                    <td>Assume the destination is a directory. Create if it does not exist. Same as appending a 
                        trailing '/' to the 'to' argument.</td>
                </tr>
                <tr>
                    <td>keep</td>
                    <td>Boolean</td>
                    <td>Keep uncompressed file after compressing.</td>
                </tr>
                <tr>
                    <td>operation</td>
                    <td>String</td>
                    <td>Set to 'append' to append files, 'copy' to copy files and 'move' to move files.
                    Set to 'list' to return a file list in options.list and perform no operations. Defaults to 'copy' if unset.</td>
                </tr>
                <tr>
                    <td>patch</td>
                    <td>Object</td>
                    <td>Expand file contents tokens using this object. Object hash containing properties to use 
                    when replacing tokens of the form ${token} in file contents.</td>
                </tr>
                <tr>
                    <td>permissions</td>
                    <td>Number</td>
                    <td>Posix style permissions mask. E.g. 0644.</td>
                </tr>
                <tr>
                    <td>relative</td>
                    <td>Boolean | String | Path</td>
                    <td>Create destination filenames relative to the path provided by the 
                    'relative' option, otherwise destination filenames include the Path value. If set to true, the destination
                     will be relative to the current directory. If set, implies flatten == false. Defaults to false.</td>
                </tr>
                <tr>
                    <td>rename</td>
                    <td>Function</td>
                    <td>Callback function to provide a new destination filename. Calling sequence:
                    Function(from, to, options): Path.</td>
                </tr>
                <tr>
                    <td>divider</td>
                    <td>Boolean</td>
                    <td>Keep uncompressed file after compressing.</td>
                </tr>
                <tr>
                    <td>strip</td>
                    <td>Boolean</td>
                    <td>Run 'strip' on the destination files.</td>
                </tr>
                <tr>
                    <td>symlink</td>
                    <td>String | Path</td>
                    <td>Create a symbolic link to the destination. If symlink has a trailing '/'
                    a link is created in the directory specified by 'symlink' using the source file 
                    basename as the link name.</td>
                </tr>
                <tr>
                    <td>trim</td>
                    <td>Number</td>
                    <td>Number of path components to trim from the start of the source filename. 
                        If set, implies flatten == false.</td>
                </tr>
                <tr>
                    <td>user</td>
                    <td>String | Number</td>
                    <td>User account name or number to use for destination files.</td>
                </tr>
            </tbody>
        </table>
        <h3>Configurable Targets Collection &mdash; me.targets.*</h3>
        <p>These properties are relevant only if the target is configurable (has configurable == true)</p>
        <table title="targets" class="ui table segment">
            <thead>
                <tr><th>Name</th><th>Description</th>
            </thead>
            <tbody>
                <tr><td>conflicts</td><td>Array of conflicting configurable targets</td></tr>
                <tr><td>description</td><td>Descriptive name of the configurable target</td></tr>
                <tr><td>requires</td><td>Array of targets to discover that are essential for this target</td></tr>
                <tr><td>discovers</td><td>Array of targets to discover that may be optionally utilized by this target</td></tr>
                <tr><td>enable</td><td>Set to true if the target was found on the system</td></tr>
                <tr><td>file</td><td>File to the MakeMe file that defined the target</td></tr>
                <tr><td>imports</td><td>Files to import for this target into the platform bin directory before building</td></tr>
                <tr><td>path</td><td>If found, the path to the configurable target directory or binary</td></tr>
                <tr><td>withpath</td><td>Path supplied via a configure --with EXTENSION=PATH command line option</td></tr>
            </tbody>
        </table>

        <a name="scripts"></a>
        <h2>Scripts Collection &mdash; me.scripts.*</h2>
        <table title="scripts" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>preblend</td><td>Array of scripts to run for the preblend event</td></tr>
                <tr><td>postload</td><td>Array of scripts to run for the postload event</td></tr>
                <tr><td>loaded</td><td>Array of scripts to run for the loaded event</td></tr>
                <tr><td>preinherit</td><td>Array of scripts to run for the preinherit event</td></tr>
                <tr><td>postconfig</td><td>Array of scripts to run for the postconfig event</td></tr>
                <tr><td>preheader</td><td>Array of scripts to run for the preheader event</td></tr>
                <tr><td>pregen</td><td>Array of scripts to run for the pregen event</td></tr>
                <tr><td>gencustom</td><td>Array of scripts to run for the gencustom event</td></tr>
            </tbody>
        </table>
        <a name="tscripts"></a>
        <h2>Target Scripts Collection &mdash; me.targets[].scripts.*</h2>
        <table title="tscripts" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>postblend</td><td>Array of scripts to run for the postblend event</td></tr>
                <tr><td>preresolve</td><td>Array of scripts to run for the preresolve event</td></tr>
                <tr><td>postresolve</td><td>Array of scripts to run for the postresolve event</td></tr>
                <tr><td>presource</td><td>Array of scripts to run for the presource event</td></tr>
                <tr><td>postsource</td><td>Array of scripts to run for the postsource event</td></tr>
                <tr><td>precompile</td><td>Array of scripts to run for the precompile event</td></tr>
                <tr><td>postcompile</td><td>Array of scripts to run for the postcompile event</td></tr>
                <tr><td>prebuild</td><td>Array of scripts to run for the prebuild event</td></tr>
                <tr><td>build</td><td>Array of scripts to run for the build event</td></tr>
                <tr><td>postbuild</td><td>Array of scripts to run for the postbuild event</td></tr>
            </tbody>
        </table>
        <a name="pscripts"></a>
        <h2>Configurable Target Scripts Collection &mdash; me.targets[].scripts.*</h2>
        <table title="pscripts" class="ui table segment">
            <thead>
                <tr><th class="two wide">Name</th>
                <th>Description</th>
            </thead>
            <tbody>
                <tr><td>without</td><td>Array of scripts to run for the without event</td></tr>
                <tr><td>config</td><td>Array of scripts to run for the config event</td></tr>
            </tbody>
        </table>
